<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<TITLE>
ImageBundle (Google Web Toolkit Javadoc)
</TITLE>

<META NAME="keywords" CONTENT="com.google.gwt.user.client.ui.ImageBundle interface">

<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../../../stylesheet.css" TITLE="Style">

<SCRIPT type="text/javascript">
function windowTitle()
{
    parent.document.title="ImageBundle (Google Web Toolkit Javadoc)";
}
</SCRIPT>
<NOSCRIPT>
</NOSCRIPT>

</HEAD>

<BODY BGCOLOR="white" onload="windowTitle();">


<!-- ========= START OF TOP NAVBAR ======= -->
<A NAME="navbar_top"><!-- --></A>
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../../../../com/google/gwt/user/client/ui/Image.html" title="class in com.google.gwt.user.client.ui"><B>PREV CLASS</B></A>&nbsp;
&nbsp;<A HREF="../../../../../../com/google/gwt/user/client/ui/ImageBundle.Resource.html" title="annotation in com.google.gwt.user.client.ui"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../../../../../index.html?com/google/gwt/user/client/ui/ImageBundle.html" target="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="ImageBundle.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;<SCRIPT type="text/javascript">
  <!--
  if(window==top) {
    document.writeln('<A HREF="../../../../../../allclasses-noframe.html"><B>All Classes</B></A>');
  }
  //-->
</SCRIPT>
<NOSCRIPT>
  <A HREF="../../../../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>


</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
  SUMMARY:&nbsp;<A HREF="#nested_class_summary">NESTED</A>&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;METHOD</FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;METHOD</FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A>
<!-- ========= END OF TOP NAVBAR ========= -->

<HR>
<!-- ======== START OF CLASS DATA ======== -->
<H2>
<FONT SIZE="-1">
com.google.gwt.user.client.ui</FONT>
<BR>
Interface ImageBundle</H2>
<DL>
<DT><B>All Known Subinterfaces:</B> <DD><A HREF="../../../../../../com/google/gwt/user/client/ui/DisclosurePanelImages.html" title="interface in com.google.gwt.user.client.ui">DisclosurePanelImages</A>, <A HREF="../../../../../../com/google/gwt/user/client/ui/HorizontalSplitPanelImages.html" title="interface in com.google.gwt.user.client.ui">HorizontalSplitPanelImages</A>, <A HREF="../../../../../../com/google/gwt/user/client/ui/MenuBar.MenuBarImages.html" title="interface in com.google.gwt.user.client.ui">MenuBar.MenuBarImages</A>, <A HREF="../../../../../../com/google/gwt/user/client/ui/TreeImages.html" title="interface in com.google.gwt.user.client.ui">TreeImages</A>, <A HREF="../../../../../../com/google/gwt/user/client/ui/VerticalSplitPanelImages.html" title="interface in com.google.gwt.user.client.ui">VerticalSplitPanelImages</A></DD>
</DL>
<HR>
<DL>
<DT><PRE>public interface <B>ImageBundle</B></DL>
</PRE>

<P>
A tag interface that is used in the generation of image bundles. An image
 bundle is a composition of multiple images into a single large image, along
 with an interface for accessing a specific image's
 <A HREF="../../../../../../com/google/gwt/user/client/ui/AbstractImagePrototype.html" title="class in com.google.gwt.user.client.ui"><CODE>prototype</CODE></A> from
 within the composition. Obtain an image bundle instance by calling
 <code>GWT.create(<i>T</i>)</code>, where <code>T</code> is an
 interface that directly or indirectly extends <code>ImageBundle</code>.
 
 <p>
 To create and use an image bundle, extend the <code>ImageBundle</code>
 interface, and add a method declaration for each image that is to be part of
 the bundle. Each method must take no parameters and must have a return type
 of
 <A HREF="../../../../../../com/google/gwt/user/client/ui/AbstractImagePrototype.html" title="class in com.google.gwt.user.client.ui"><CODE>AbstractImagePrototype</CODE></A>.
 The image name can optionally be specified using the <A HREF="../../../../../../com/google/gwt/user/client/ui/ImageBundle.Resource.html" title="annotation in com.google.gwt.user.client.ui"><CODE>ImageBundle.Resource</CODE></A>
 annotation. (Note that the <code>gwt.resource</code> javadoc metadata tag
 supporting in GWT 1.4 has been superceded by the <code>Resource</code>
 annotation.) Valid image name extensions are <code>png</code>,
 <code>gif</code>, or <code>jpg</code>. If the image name contains '/'
 characters, it is assumed to be the name of a resource on the classpath,
 formatted as would be expected by <code>
  <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String)">ClassLoader.getResource(String)</a>.
 </code>
 Otherwise, the image must be located in the same package as the user-defined
 image bundle.
 </p>
 
 <p>
 The easiest way to create an image bundle is to omit the <A HREF="../../../../../../com/google/gwt/user/client/ui/ImageBundle.Resource.html" title="annotation in com.google.gwt.user.client.ui"><CODE>ImageBundle.Resource</CODE></A>
 annotation, and name the method the same as the image name, excluding the
 extension. When the image name is inferred in this manner, the image name's
 extension is assumed to be either <code>png</code>, <code>gif</code>,
 or <code>jpg</code>, and the image location must be in the same package as
 the user-defined image bundle. In the event that there are multiple image
 files that have the same name with different extensions, the order of
 extension precedence is <code>png</code>, <code>gif</code>,
 <code>jpg</code>.
 
 <h3>Example</h3>
 
 <pre class="code">
 public interface MyImageBundle extends ImageBundle {

   /**
    * Notice that the Resource annotation is not present, 
    * so the method name itself is assumed to match the associated 
    * image filename.
    *
    * One of btn_submit_icon.png, btn_submit_icon.gif, or 
    * btn_submit_icon.jpg must be located in the same package 
    * as MyImageBundle.
    *&#47; 
   public AbstractImagePrototype btn_submit_icon();

   // No doc comment is required if you want the default 
   // name-matching behavior.
   public AbstractImagePrototype cancelButtonIcon();
 }
 </pre>
 
 </p>
 
 <p>
 An image bundle that uses the <code>Resource</code> annotation to specify
 image names might look something like this:
 
 <pre class="code">
 public interface MyImageBundle extends ImageBundle {

   /**
    * The resource annotation contains no '/' characters, so 
    * btn_submit_icon.gif must be located in the same 
    * package as MyImageBundle.
    *&#47;
   <code>@Resource("btn_submit_icon.gif")</code>
   public AbstractImagePrototype submitButtonIcon();

   /**
    * btn_cancel_icon.png must be located in the package 
    * com.mycompany.myapp.icons (which must be on the classpath).
    *&#47;
   <code>@Resource("com/mycompany/myapp/icons/btn_cancel_icon.png")</code>
   public AbstractImagePrototype cancelButtonIcon();
 }
 </pre>
 
 </p>
 
 <p>
 Here is how MyImageBundle might be used in an application:
 
 <pre class="code">
  ...

  // Create a new instance of MyImageBundle using GWT.create.
  // This only needs to be done once - a reference to myImageBundle can
  // be kept for use by other parts of the application.
  MyImageBundle myImageBundle = GWT.create(MyImageBundle.class);

  // Retrieve the image prototypes from myImageBundle.
  AbstractImagePrototype submitButtonImgPrototype = myImageBundle.btn_submit_icon();
  AbstractImagePrototype cancelButtonImgPrototype = myImageBundle.cancelButtonIcon();

  // Add the images that are created based on the prototypes to the panel.
  panel.add(submitButtonImgPrototype.createImage());
  panel.add(cancelButtonImgPrototype.createImage());

 ...
 </pre>
 
 </p>
 
 <h3>Security Warning: Image Bundle's use of the javax.image.imageio Classes</h3>
 Certain versions of the JVM are susceptible to a vulnerability in the
 javax.image.imageio classes, which are generally used to parse images. These
 classes are used by image bundle's implementation to combine all of the
 images into a single composite image.
 
 <p>
 It is possible that the vulnerability could be exploited by using a specially
 crafted image as part of an image bundle. To prevent this type of attack from
 occurring, use a version of the JVM that includes a fix for this
 vulnerability. See the following link for more information:
 </p>
 
 <pre>
 <a href="http://sunsolve.sun.com/search/document.do?assetkey=1-26-102934-1">http://sunsolve.sun.com/search/document.do?assetkey=1-26-102934-1</a>
 </pre>
 
 <p>
 Alternatively, if the images to be used in the bundle are trusted, then it is
 not necessary to upgrade the JVM.
 </p>
 
 <h3>Caching Recommendations for Image Bundle Files</h3>
 Since the filename for the image bundle's composite image is based on a hash
 of the file's contents, the server can tell the browser to cache the file
 permanently.
 
 <p>
 To make all image bundle files permanently cacheable, set up a rule in your
 web server to emit the <code>Expires</code> response header for any files
 ending with <code>".cache.*"</code>. Such a rule would automatically match
 generated image bundle filenames (e.g.
 <code>320ADF600D31858000C612E939F0AD1A.cache.png</code>). The HTTP/1.1
 specification recommends specifying date of approximately one year in the
 future for the <code>Expires</code> header to indicate that the resource is
 permanently cacheable.
 </p>
 
 <h3>Using Security Constraints to Protect Image Bundle Files</h3>
 When a web application has a security constraint set for the composite image,
 web application servers may change the image's HTTP response headers so that
 web browsers will not cache it. For example, Tomcat and Glassfish set the
 HTTP response headers <code>Pragma: No-cache</code>,
 <code>Cache-Control: None</code>, and
 <code>Expires: Thu, 1 Jan 1970 00:00:00</code> (or some other date in the
 past).
 
 <p>
 This can lead to performance problems when using image bundles, because the
 large composite image will be re-requested unecessarily. In addition,
 <code>clear.cache.gif</code>, which is a blank image used by the image
 bundle implementation, will be re-requested as well. While some browsers will
 only re-request these images for each page load, others will re-request them
 for each image on the page that is part of an image bundle.
 </p>
 
 There are several ways to work around this issue:
 
 <ol>
 <li> Modify the servlet which serves <code>png</code> and <code>gif</code>
 files so that it explicitly sets the <code>Pragma</code>,
 <code>Cache-Control</code>, and <code>Expires</code> headers. The
 <code>Pragma</code> and <code>Cache-Control</code> headers should be
 removed. The <code>Expires</code> header should be set according to the
 caching recommendations mentioned in the previous section. </li>
 <li> If using Tomcat, use the <code>disableProxyCaching</code> property in
 your web application configuration file to prevent the <code>Pragma</code>,
 <code>Cache-Control</code>, and <code>Expires</code> headers from being
 changed by the server. Refer to your web application server's documentation
 for more information. </li>
 <li> Exclude the image bundle's composite image from the web application's
 security constraint. </li>
 <li> If there is sensitive data in any of the images in the image bundle,
 exclude that image from the bundle and include it in the web application's
 security constraint. Then, rebuild the image bundle, and exclude the updated
 bundle's composite image from the security constraint. </li>
 </ol>
 
 <h3>Image Bundles and the HTTPS Protocol</h3>
 There is an issue with displaying image bundle images in Internet Explorer
 when:
 
 <ul>
 <li>The image bundle's composite image is requested using the HTTPS
 protocol, and</li>
 <li>The web application has a security constraint set for the composite
 image</li>
 </ul>
 
 This issue is known to occur with the web application servers Tomcat and
 Glassfish.
 
 <p>
 The native format for the composite image is <code>png</code>, and
 versions of Internet Explorer prior to 7 cannot render <code>png</code>
 transparerency. To get around this problem, we make use of a plugin built
 into the operating system.
 </p>
 
 <p>
 Internet Explorer specifies that files which require a plugin for viewing
 must be cached by the browser. That way, the plugin can read the cached file
 from the disk. Whenever the composite image is protected by a security
 constraint, the web application server sets caching headers on the response
 to prevent the browser from caching the image (see the previous section for
 details).
 </p>
 
 <p>
 When using the HTTP protocol, Internet Explorer will disregard the
 <code>Pragma: No-cache</code> and <code>Cache-Control: None</code>
 headers, and will cache the image. However, When using the HTTPS protocol,
 Internet Explorer will enforce these headers, and will not cache the image.
 Since the composite image is not stored on disk, the plugin is unable to
 render it, and all of the images in the application which rely on the
 composite image will not be displayed.
 </p>
 
 <p>
 To work around this issue, follow the recommendations outlined in the
 previous section.
 </p>
 
 <h3>For More Information</h3>
 See the GWT Developer Guide for an introduction to image bundles.
<P>

<P>
<DL>
<DT><B>See Also:</B><DD><A HREF="../../../../../../com/google/gwt/user/client/ui/AbstractImagePrototype.html" title="class in com.google.gwt.user.client.ui"><CODE>AbstractImagePrototype</CODE></A>, 
<A HREF="../../../../../../com/google/gwt/user/client/ui/Image.html#Image(java.lang.String, int, int, int, int)"><CODE>Image.Image(String, int, int, int, int)</CODE></A>, 
<A HREF="../../../../../../com/google/gwt/user/client/ui/Image.html#setVisibleRect(int, int, int, int)"><CODE>Image.setVisibleRect(int, int, int, int)</CODE></A>, 
<A HREF="../../../../../../com/google/gwt/user/client/ui/Image.html#setUrlAndVisibleRect(java.lang.String, int, int, int, int)"><CODE>Image.setUrlAndVisibleRect(String, int,
      int, int, int)</CODE></A></DL>
<HR>

<P>
<!-- ======== NESTED CLASS SUMMARY ======== -->

<A NAME="nested_class_summary"><!-- --></A>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Nested Class Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;interface</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../../../../com/google/gwt/user/client/ui/ImageBundle.Resource.html" title="annotation in com.google.gwt.user.client.ui">ImageBundle.Resource</A></B></CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Explicitly specifies a file name or path to the image resource to be
 associated with a method in an <A HREF="../../../../../../com/google/gwt/user/client/ui/ImageBundle.html" title="interface in com.google.gwt.user.client.ui"><CODE>ImageBundle</CODE></A>.</TD>
</TR>
</TABLE>
&nbsp;
<P>
<!-- ========= END OF CLASS DATA ========= -->
<HR>


<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../../../../com/google/gwt/user/client/ui/Image.html" title="class in com.google.gwt.user.client.ui"><B>PREV CLASS</B></A>&nbsp;
&nbsp;<A HREF="../../../../../../com/google/gwt/user/client/ui/ImageBundle.Resource.html" title="annotation in com.google.gwt.user.client.ui"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../../../../../index.html?com/google/gwt/user/client/ui/ImageBundle.html" target="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="ImageBundle.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;<SCRIPT type="text/javascript">
  <!--
  if(window==top) {
    document.writeln('<A HREF="../../../../../../allclasses-noframe.html"><B>All Classes</B></A>');
  }
  //-->
</SCRIPT>
<NOSCRIPT>
  <A HREF="../../../../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>


</FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
  SUMMARY:&nbsp;<A HREF="#nested_class_summary">NESTED</A>&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;METHOD</FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL:&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;METHOD</FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->

<HR>

</BODY>
</HTML>
